---
title: Astro 업그레이드
description: Astro를 업그레이드하는 방법
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import Version from '~/components/Version.astro';

이 가이드에서는 Astro 버전 및 관련 의존성을 업데이트하는 방법, 버전별 변경 사항을 확인하는 방법, Astro의 버전 관리 시스템과 해당 문서 업데이트를 이해하는 방법을 다룹니다.

## 무엇이 바뀌었나요?

Astro의 최신 릴리스 버전은 <Version pkgName="astro" />입니다.

[Astro 변경 로그](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md)에서 모든 변경 사항의 전체 목록을 확인할 수 있으며, [업그레이드 가이드](#업그레이드-가이드)에서 각 새 [메이저 버전](#메이저-변경)으로 업그레이드하기 위한 중요한 지침을 확인할 수 있습니다.

## 최신 버전으로 업그레이드

패키지 관리자를 사용하여 다음 명령 한 줄로 Astro 프로젝트 버전과 모든 공식 통합을 최신 버전으로 업데이트하세요.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # Astro와 공식 통합을 함께 업그레이드합니다.
  npx @astrojs/upgrade
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # Astro와 공식 통합을 함께 업그레이드합니다.
  pnpm dlx @astrojs/upgrade
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # Astro와 공식 통합을 함께 업그레이드합니다.
  yarn dlx @astrojs/upgrade
  ```
  </Fragment>
</PackageManagerTabs>

### 수동 업그레이드

Astro와 통합을 현재 버전으로 수동으로 업데이트하려면 패키지 관리자에 적합한 명령을 사용하세요.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # 예시: React 및 Partytown 통합과 함께 Astro를 업그레이드합니다.
  npm install astro@latest @astrojs/react@latest @astrojs/partytown@latest
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # 예시: React 및 Partytown 통합과 함께 Astro를 업그레이드합니다.
  pnpm add astro@latest @astrojs/react@latest @astrojs/partytown@latest
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # 예시: React 및 Partytown 통합과 함께 Astro를 업그레이드합니다.
  yarn add astro@latest @astrojs/react@latest @astrojs/partytown@latest
  ```
  </Fragment>
</PackageManagerTabs>

### 특정 버전 설치

특정 [Astro 버전](https://www.npmjs.com/package/astro?activeTab=versions) 또는 통합을 설치하려면 패키지 관리자에 적합한 명령을 사용하세요.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install astro@4.5.3 @astrojs/react@3.0.10
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add astro@4.5.3 @astrojs/react@3.0.10
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add astro@4.5.3 @astrojs/react@3.0.10
  ```
  </Fragment>
</PackageManagerTabs>

## 문서 업데이트

이 문서는 [마이너 릴리스](#마이너-변경) 및 [메이저 버전 릴리스](#메이저-변경)마다 업데이트됩니다. 새로운 기능이 추가되거나 기존 사용법이 변경되면, 문서는 **Astro의 현재 동작**을 반영하도록 업데이트됩니다. 프로젝트가 업데이트되지 않은 경우, 일부 동작이 최신 문서와 일치하지 않을 수 있습니다.

문서에 새로운 기능이 추가될 때, 해당 기능이 추가된 특정 버전 번호가 함께 표시됩니다. 즉, Astro의 최신 릴리스로 업데이트하지 않은 경우 문서에 설명된 일부 기능을 사용하지 못할 수 있습니다. 새 기능을 사용하기 전에 항상 `Added in:` 버전 번호를 확인하고 프로젝트가 업데이트되었는지 확인하세요!

Astro의 최신 메이저 버전으로 업그레이드하지 않은 경우, Astro 문서와 프로젝트의 동작 간에 상당한 차이가 발생할 수 있습니다. 가능한 한 빨리 Astro의 현재 메이저 버전으로 업그레이드하는 것이 좋습니다. 이전 버전의 코드와 문서는 모두 지원되지 않습니다.

### 업그레이드 가이드

[메이저 버전 릴리스](#메이저-변경) 후에는 중요한 변경 사항에 대한 정보와 프로젝트 코드를 업그레이드하는 방법에 대한 지침이 포함된 **업그레이드 가이드**를 찾을 수 있습니다.

Astro 주요 문서 페이지는 항상 **Astro의 최신 릴리스 버전에 대해 정확합니다**. 이전 버전의 작동 방식에 대해 설명하거나 비교하지 않으며, 업데이트되거나 변경된 동작을 강조하지도 않습니다.

아래의 업그레이드 가이드에서 변경 사항에 대한 설명과 새 버전과 이전 버전을 비교한 내용을 확인하세요. 업그레이드 가이드에는 주요 변경 사항, 더 이상 사용되지 않는 기능, 기능 제거 및 대체, 업데이트된 사용법 안내 등 사용자 코드 변경이 필요할 수 있는 모든 내용이 포함되어 있습니다. Astro의 각 변경 사항에는 프로젝트 코드를 성공적으로 업데이트하는 데 도움이 되는 "무엇을 해야 하나요?" 섹션이 포함되어 있습니다.

- [v5로 업그레이드](/ko/guides/upgrade-to/v5/)
- [v4로 업그레이드](/ko/guides/upgrade-to/v4/)
- [v3로 업그레이드](/ko/guides/upgrade-to/v3/)
- [v2로 업그레이드](/ko/guides/upgrade-to/v2/)
- [v1로 업그레이드](/ko/guides/upgrade-to/v1/)

### 이전 문서 (유지 관리되지 않음)

이전 버전의 Astro에 대한 문서는 유지 관리되지 않지만, 정적 스냅샷으로 제공됩니다. 프로젝트를 업그레이드할 수 없지만 가이드 및 참조가 필요한 경우 이러한 버전의 문서를 사용하세요.

- [유지 관리되지 않는 v4.16.17 스냅샷](https://v4.docs.astro.build/en/getting-started/)
- [유지 관리되지 않는 v3.6.3 스냅샷](https://docs-git-v3-docs-unmaintained-astrodotbuild.vercel.app/)
- [유지 관리되지 않는 v2.10.15 스냅샷](https://deploy-preview-4405--astro-docs-2.netlify.app/en/getting-started/)

## 의미론적 버전 관리

Astro는 개발자가 릴리스에 버전 번호를 할당하는 방법을 결정하기 위해 사용하는 규칙 집합인 [의미론적 버전 관리](https://semver.org/)를 최대한 준수하려고 노력합니다. 의미론적 버전은 사용자가 한 버전에서 다음 버전으로 예상할 수 있는 변경 종류를 알려주기 위해 예측 가능한 패턴을 따릅니다.

의미론적 버전 관리는 소프트웨어 버전 번호에 `X.Y.Z` 패턴을 적용합니다. 이러한 값은 **메이저 (X)**, **마이너 (Y)** 및 **패치 (Z)** 업데이트를 나타냅니다.

### 패치 변경

패치 변경은 가장 적은 중단을 일으키는 변경입니다. Astro를 사용하는 방식을 변경하지 않으며, 업데이트 시 사용자 코드 변경이 필요하지 않습니다.

Astro가 "패치" 버전을 발행하면 마지막 숫자가 증가합니다. (예: `astro@4.3.14` -> `astro@4.3.15`)

패치는 다음과 같은 이유로 릴리스될 수 있습니다.

- Astro의 기능을 변경하지 않는 내부 변경:
  - 리팩터링
  - 성능 향상
  - 테스트 커버리지 증가 또는 변경
  - 명시된 문서 및 예상 동작과 일치
- 로깅 및 오류 메시지 개선
- 실패한 릴리스 후 재릴리스

패치 변경에는 사용자가 기존의 의도하지 않거나 바람직하지 않은 동작을 활용하는 경우를 포함하여 **대부분의 버그 수정**도 포함됩니다.

### 마이너 변경

마이너 릴리스는 주로 사용자가 사용해 볼 수 있는 새로운 기능과 개선 사항을 도입하지만, 코드를 변경할 필요는 없습니다. 일부 기존 기능은 마이너 릴리스에서 **더 이상 사용되지 않는 기능**으로 (향후 버전에서 삭제될 예정이지만 계속 작동하는 기능) 지정될 수 있습니다. 따라서 최종 제거에 대비할 수 있는 기회를 제공합니다.

마이너 릴리스에는 다음과 같은 변경 사항이 포함됩니다.

- 향후 메이저 릴리스에서 제거될 것이라는 경고와 함께 기존 기능/옵션의 **더 이상 사용되지 않음** 처리
- 새로운 기능 도입
- 통합 훅에 새로운 옵션 도입
- 특히 새로운 어댑터 생성에 사용되는 `astro/app`에 새로운 기능 도입

마이너 릴리스에는 동시에 더 작은 패치 변경도 포함될 수 있습니다.

### 메이저 변경

메이저 릴리스에는 최소한 일부 기존 코드에 대한 주요 변경 사항이 포함됩니다. 이러한 주요 변경 사항은 항상 Astro의 ["vX로 업그레이드" 가이드](#업그레이드-가이드)에 문서화되어 있습니다.

메이저 릴리스를 통해 Astro는 내부 논리뿐만 아니라 의도된 동작 및 사용법까지 중요한 변경을 수행할 수 있습니다. 문서는 최신 버전만 반영하도록 업데이트되며, 아직 업그레이드되지 않은 이전 프로젝트의 기록으로 **정적이고 유지 관리되지 않는 이전 문서 스냅샷**을 제공합니다.

메이저 릴리스에는 다음과 같은 변경 사항이 포함됩니다.

- 이전에 더 이상 사용되지 않는 기능 제거
- 기존 기능 변경
- 통합 훅의 기존 옵션 변경
- 특히 새로운 어댑터 생성에 사용되는 `astro/app`의 기존 옵션 및 기능 변경

메이저 릴리스에는 일반적으로 마이너 또는 패치 릴리스에서 별도로 릴리스되는 일부 비호환성 변경 및 개선 사항도 포함될 수 있습니다.

### 예외

- **실험적인 기능**. 의미론적 버전 관리를 따르지 않고 Astro 버전을 릴리스하면 Astro 개발자는 실험적인 기능을 개발하는 동안 최대한의 유연성을 확보하여 탐색하고, 심지어 방향을 근본적으로 변경할 수 있습니다. 따라서 이러한 기능의 동작은 마이너 및 패치 변경에서 중단될 수 있습니다.
  
  이러한 기능에는 일반적으로 진행 중인 공개 [검토 요청 (RFC) 3단계](https://github.com/withastro/roadmap#stage-3-rfc--development)가 함께 제공됩니다. 베타 사용자는 업데이트를 팔로우하고 토론에 대한 초기 피드백을 남겨 이러한 기능 개발을 안내를 도울 것으로 예상됩니다.
  
  이러한 기능이 실험 기간을 벗어나면 일반적인 의미론적 버전 관리 계약을 따릅니다.

- **문서 개선** (예: 참조 및 오류 메시지). `docs` 리포지토리의 소스에서 빌드됩니다. 이를 통해 Astro는 문서 소스 콘텐츠가 기본 `astro` 리포지토리에 저장된 경우 문서 수정 및 개선 사항을 빠르게 업데이트할 수 있습니다.

### Node.js 지원 및 업그레이드 정책

#### 지원

- Astro는 [**Node.js의 최신 _Maintenance_ LTS 버전**](https://nodejs.org/en/about/previous-releases#release-schedule)을 지원합니다.
- Astro는 [**Node.js의 현재 _Active_ LTS 버전**](https://nodejs.org/en/about/previous-releases#release-schedule)을 지원합니다.
- Astro는 홀수 버전의 Node.js를 지원할 수 있습니다.

#### 업그레이드

다음 규칙은 Astro가 Node.js 버전에 대한 지원을 중단, 삭제 또는 추가할 수 있는 시기를 정의합니다.

- 홀수 버전의 Node.js는 다음 짝수 버전의 Node.js가 게시될 때 더 이상 사용되지 않거나 삭제될 수 있습니다. 이 변경 사항은 Astro Core 팀이 결정한 합리적인 연장 지원 기간 후 Astro의 **마이너** 릴리스에서 발생할 수 있습니다.
- Node.js의 최소 **_Maintenance_ LTS** (동일한 주버전 범위와 함께, 예를 들어 `v18.14.*`에서 `v18.20.*`로) 버전 업그레이드는 Astro의 **부** 릴리스에서 발생할 수 있습니다.
- 최소 **_Maintenance_ LTS** 버전 (동일한 메이저 범위 내, 예를 들어 `v18.14.*`에서 `v18.20.*`)의 Node.js 업그레이드는 Astro의 **마이너** 릴리스에서 발생할 수 있습니다.
  - 보안 예외: **Astro에 영향을 미치는** Node.js의 보안 결함이 발견되어 수정된 경우, Core 팀은 **패치** 릴리스에서 최소 **_Maintenance_ LTS** 버전을 높일 수 있습니다.
- 마이너 또는 메이저 버전의 Node.js 업그레이드 (Maintenance LTS **제외**)는 Astro의 메이저 버전에서만 발생합니다.
  - 보안 예외: **Astro에 영향을 미치는** Node.js의 보안 결함이 발견되어 수정된 경우, Core 팀은 **마이너** 릴리스에서 최소 버전을 높일 수 있습니다.

### 연장된 유지 관리

Core 팀은 이전 메이저 버전에 대해 **보안 수정 사항에 한하여** 연장된 유지 관리를 제공합니다. 즉, 현재 메이저 버전이 `v4.*`인 경우 Core 팀은 보안 수정 사항을 백포트하고 새로운 `v3.*` 릴리스를 발행합니다.
